Table of Contents Previous Section

Using the WOAction Object in Nested Components

In the most common case, a component (that is, a unit that's constructed from a script, an HTML template, and a declarations file) corresponds to a single, dynamically generated page in an application. Sometimes, however, one component is nested inside of another. Such components, such as a calendar or a footer component, may be suited for use in a range of different applications.

WebScript provides a mechanism for constructing components that can be reused without having to be rewritten. This mechanism is WOAction, which allows you to separate a user action (such as clicking on a hyperlink) from the method it invokes. This allows a nested (child) component to be used with different parent components by enabling each parent to respond to the user action in its own way.

The WOAction object allows nested child components to send callback messages to their parents. This is how it works:

1. The parent page declares the component in its declarations file.
   

   For example, the Main page in the Component example (see the WebObjects examples) has this declaration in its Main.wod declarations file:

     PALETTE:Palette {
       selection = number;
       callBack = displaySelection;
     };
   

   The callBack attribute specified in the declaration takes as its value a method (displaySelection) that is triggered when the child component sends the callBack object an invoke message. Through this mechanism the child component is able to message the parent (in this case, the Main page).

2. The child component's script uses the action keyword to declare that the callBack attribute specified in the parent's declarations file is a WOAction object:
   

   action callBack;
   

3. The child component script then sends the WOAction object (in this example, callBack) an invoke message, which tells the object to invoke its associated method (in this example, displaySelection).
   

   For example, here's an excerpt from the child component script Palette.wos:

   action callBack;
   
   - click {
       selection = digit;
       return [callBack invoke];
   }
   

When the user clicks on a digit in the browser, the child component's click method is triggered. This sets the value of the selection variable to the digit the user clicked on. Since the selection variable of the child component is tied to the number variable of the parent (in the selection = number statement in the declaration), the number variable is modified accordingly. Next, the click method sends the WOAction object callBack an invoke message. This in turn invokes the displaySelection method in the parent's script Main.wos. Finally, the displaySelection method generates a new HTML page that reflects the digit clicked by the user.

You can use this technique in a single application in which multiple parent components interact with a child component differently. The following statements give examples of what this would entail in the parents' declarations files and the child's script:

Component declaration in Parent1.wod

COMPONENT:component {
    childVar = parent1Var;
    callBack = endWorldHunger;
};

Component declaration in Parent2.wod

COMPONENT:component {
    childVar = parent2Var;
    callBack = lookOutForNumberOne;
};

The associated method in Child.wos

action callBack;

- click 
{
    childVar = newValue;
    return [callBack invoke];
}

Table of Contents Next Section